---
title: Testes
description: Uma introdução para testes no Astro
i18nReady: true
---
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'


Fazer testes o ajuda a escrever e manter código Astro em funcionamento. O Astro suporta muitas ferramentas populares para testes de unidade, testes de componente e testes de ponta a ponta (e2e), incluindo Jest, Mocha, Jasmine, [Cypress](https://cypress.io) e [Playwright](https://playwright.dev). Você pode até mesmo instalar bibliotecas de testes específicos de frameworks como a React Testing Library, para testar seus componentes de frameworks de UI.

Frameworks de testes permitem que você declare **afirmações** ou **expectativas** sobre como seu código deve se comportar em situações específicas e, em seguida, as compare com o comportamento real do seu código atual.

## Vitest

Vitest é um framework de testes de unidade nativo do Vite com suporte a ESM, TypeScript e JSX fornecido pelo esbuild.

Use o auxiliar `getViteConfig()` do Astro no seu arquivo de configuração [`vitest.config.ts`](https://vitest.dev/config/) para configurar o Vitest com as configurações do seu projeto Astro.

```js
// vitest.config.ts
import { getViteConfig } from 'astro/config';

export default getViteConfig({
  test: {
    // opções de configuração do Vitest
  },
});
```

Veja o [template inicial de Astro + Vitest](https://github.com/withastro/astro/tree/latest/examples/with-vitest) no GitHub.

## Cypress

Cypress é uma ferramenta de testes front-end construído para a web moderna. Cypress permite você escrever testes de ponta a ponta para o seu site em Astro.

### Instalação

Você pode instalar Cypress usando o gerenciador de pacotes da sua escolha.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npm install -D cypress
  ```

  Isso vai instalar Cypress localmente como uma dependências de desenvolvimento para seu projeto.
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  pnpm add cypress --save-dev
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  yarn add cypress --dev
  ```
  </Fragment>
</PackageManagerTabs>

### Configuração

Na raiz do seu projeto, crie um arquivo `cypress.config.js` com o seguinte conteúdo:

```js title="cypress.config.js"
import { defineConfig } from 'cypress'

export default defineConfig({
  e2e: {
    supportFile: false
  }
})
```

### Crie seu primeiro teste do Cypress

1. Escolha uma página para testar. Este exemplo vai testar a página de exemplo `index.astro` abaixo.

    ```html title="src/pages/index.astro"
    ---
    ---
    <html lang="pt-BR">
      <head>
        <title>Astro e incrível!</title>
        <meta name="description" content="Extraia conteúdo de qualquer lugar e sirva-o rapidamente com a arquitetura em ilhas de última geração do Astro." />
      </head>
      <body>
      <h1>Olá mundo do Astro</h1>
      </body>
    </html>
    ```

2. Crie um arquivo `index.cy.js` na pasta `cypress/e2e`. Use o seguinte teste no arquivo para verificar que o título da página e o cabeçalho estão corretos.

    ```js title="cypress/e2e/index.cy.js"
    it('títulos estão corretos', () => {
      const pagina = cy.visit('http://localhost:4321');

      pagina.get('title').should('have.text', 'Astro e incrível!')
      pagina.get('h1').should('have.text', 'Olá mundo do Astro');
    });
    ```

    :::tip[defina um baseUrl]
    Você pode definir [`"baseUrl": "http://localhost:4321"`](https://docs.cypress.io/guides/end-to-end-testing/testing-your-app#Step-3-Configure-Cypress) no arquivo de configuração `cypress.config.js` para usar `cy.visit("/")` ao invés de `cy.visit("http://localhost:4321/")` para uma URL mais conveniente.
    :::

### Executando seus testes do Cypress

Cypress pode executar a partir da linha de comando ou do aplicativo Cypress. O aplicativo fornece uma interface visual para executar e debuggar seus testes.

Primeiro, inicie o servidor de desenvolvimento para que o Cypress possa acessar seu site ao vivo.

Para executar nosso testes do exemplo anterior usando a linha de comando, execute o seguinte comando:

```shell
npx cypress run
```

Alternativamente, execute o teste usando o aplicativo Cypress, execute o seguinte comando:

```shell
npx cypress open
```

Uma vez que o aplicativo Cypress for lançado, escolha **E2E Testing**, então selecione o navegador para ser usado para executar os testes.

Uma vez que a execução do teste tenha finalizado, você deve ver algumas marcações verdes na saída confirmando que seus testes passaram:

```shell title="Saída do npx cypress run"
Running:  index.cy.js                                                                     (1 of 1)


✓ títulos estão corretos (107ms)

1 passing (1s)
```

:::note[falhe o teste]
Para checar que seu teste realmente funciona, você pode alterar a seguinte linha no arquivo `index.astro`:

 ```astro title="src/pages/index.astro" del={2} ins={3}
  <body>
    <h1>Olá mundo do Astro</h1>
    <h1>Olá do Astro</h1>
  </body>
```

Então execute o teste novamente. Você deve ver um "x" vermelho na saída confirmando que seu teste falhou.
:::

### Próximos passos

Mais informações sobre o Cypress podem ser encontradas nos links abaixo:

- [Introdução ao Cypress](https://docs.cypress.io/guides/basics/introduction-to-cypress)
- [Testando Seu App](https://docs.cypress.io/guides/end-to-end-testing/testing-your-app)

## Playwright

Playwright é um framework de testes de ponta a ponta para aplicações web modernas. Use a API do Playwright com JavaScript ou TypeScript para testar seu código Astro em todos os motores de renderização modernos, incluindo Chromium, WebKit e Firefox.

### Instalação

Você pode começar e executar seus testes usando a [extensão do VS Code](https://playwright.dev/docs/getting-started-vscode).

Como alternativa, você pode instalar o Playwright dentro do seu projeto Astro usando o gerenciador de pacotes de sua escolha. Siga as etapas da CLI para escolher JavaScript/TypeScript, nomear sua pasta de testes e opcionalmente, adicionar um fluxo de trabalho do GitHub Actions.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npm init playwright@latest
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  pnpm dlx create-playwright
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  yarn create playwright
  ```
  </Fragment>
</PackageManagerTabs>

### Crie seu primeiro teste com Playwright

1. Escolha uma página para testar. Este exemplo vai testar a página de exemplo `index.astro` abaixo.

    ```html title="src/pages/index.astro"
    ---
    ---
    <html lang="pt-BR">
      <head>
        <title>Astro é incrível!</title>
        <meta name="description" content="Extraia conteúdo de qualquer lugar e sirva-o rapidamente com a arquitetura em ilhas de última geração do Astro." />
      </head>
      <body></body>
    </html>
    ```

1. Crie uma nova pasta e adicione o seguinte arquivo de teste em `src/test`. Copie e cole o seguinte teste no arquivo para verificar se os metadados da página estão corretos. Atualize o valor do `<title>` da página para corresponder à página que você está testando.

    ```jsx title="src/test/index.spec.ts" "Astro é incrível!"
    import { test, expect } from '@playwright/test';

    test('metadados estão corretos', async ({ page }) => {
      await page.goto("http://localhost:4321/");

      await expect(page).toHaveTitle('Astro é incrível');
    });
    ```

    :::tip[Defina a URL base]
    Você pode definir [`"baseURL": "http://localhost:4321"`](https://playwright.dev/docs/api/class-testoptions#test-options-base-url) no arquivo de configuração `playwright.config.ts` para usar `page.goto("/")` ao invés de `page.goto("http://localhost:4321/")` em prol de uma URL mais conveniente.
    :::

### Executando seus testes com Playwright

Você pode executar um único teste ou vários de uma vez, testando em um ou em vários navegadores. Por padrão, os resultados dos seus testes serão mostrados no terminal. Como opção, você pode abrir o HTML Test Reporter para mostrar um relatório completo e filtrar os resultados dos testes.

1. Para executar nosso teste do exemplo anterior usando a linha de comando, use o comando `test`. Opcionalmente, inclua o nome do arquivo para executar um único teste:

    ```sh
    npx playwright test index.spec.ts
    ```

1. Para ver o HTML Test Report completo, abra-o usando o seguinte comando:

    ```sh
    npx playwright show-report
    ```

:::tip
Execute seus testes no seu código em produção para estar mais próximo ao seu site real após deploy.
:::

#### Avançado: Iniciando um servidor web de desenvolvimento durante os testes

Você também pode fazer com que o Playwright inicie seu servidor ao executar seu script de testes usando a opção de [`webServer`](https://playwright.dev/docs/test-advanced#launching-a-development-web-server-during-the-tests) no arquivo de configuração do Playwright.

Aqui está um exemplo da configuração e dos comandos necessários utilizando o npm:

1. Adicione um script de teste no arquivo `package.json` na raiz do projeto, como `"test:e2e": "playwright test"`.
1. Em `playwright.config.ts`, adicione o objeto `webServer` e atualize o valor de `command` para `npm run preview`.

    ```js title="playwright.config.ts" ins={4-9} "npm run preview"
    import { defineConfig } from '@playwright/test';

    export default defineConfig({
      webServer: {
        command: 'npm run preview',
        url: 'http://localhost:4321/',
        timeout: 120 * 1000,
        reuseExistingServer: !process.env.CI,
      },
      use: {
        baseURL: 'http://localhost:4321/',
      },
    });
    ```

1. Execute `npm run build`, e em seguida execute `npm run test:e2e` para rodar os testes do Playwright.

Mais informações sobre o Playwright podem ser encontradas nos links abaixo:

- [Getting started with Playwright](https://playwright.dev/docs/intro)
- [Use a development server](https://playwright.dev/docs/test-webserver#configuring-a-web-server)
